Skip Headers

Oracle® Call Interface Programmer's Guide, 10g Release 2 (10.2) Part Number B14250-02 |
Home | Book List | Contents | Index | Master Index | Feedback

Previous | Next
| View PDF

# OCI Any Data Set Interface Functions

This section describes the Any Data Set Interface functions.

Table 20-7 Any Data Set Functions

Function/Page | Purpose
--- | ---
OCIAnyDataSetAddInstance() | Adds a new skeleton instance to the `OCIAnyDataSet` and all the attributes of the instance are set to `NULL`.
OCIAnyDataSetBeginCreate() | Allocates an `OCIAnyDataSet` for the given duration and initializes it with the type information.
OCIAnyDataSetDestroy() | Frees the `OCIAnyDataSet`.
OCIAnyDataSetEndCreate() | Marks the end of `OCIAnyDataSet` creation.
OCIAnyDataSetGetCount() | Gets the number of instances in the `OCIAnyDataSet`
OCIAnyDataSetGetInstance() | Returns the `OCIAnyData` corresponding to an instance at the current position and updates the current position.
OCIAnyDataSetGetType() | Gets the type corresponding to an `OCIAnyDataSet`.

## OCIAnyDataSetAddInstance()

Purpose

Adds a new skeleton instance to the `OCIAnyDataSet` and all the attributes of the instance are set to `NULL`.

Syntax

    sword OCIAnyDataSetAddInstance ( OCISvcCtx      *svchp,
                                     OCIError       *errhp,
                                     OCIAnyDataSet  *data_set,
                                     OCIAnyData     **data );

Parameters

svchp (IN)

  The OCI service context.

errhp (IN/OUT)

  The OCI error handle. If there is an error, it is recorded in `err` and this function returns `OCI_ERROR`. Obtain diagnostic information by calling `OCIErrorGet()`.

data_set (IN/OUT)

  `OCIAnyDataSet` to which a new instance is added.

data (IN/OUT)

  `OCIAnyData` corresponding to the newly added instance. If `(*data)` is `NULL`, a new `OCIAnyData` will be allocated for the same duration as the `OCIAnyDataSet`. If `(*data)` is not `NULL`, it will be reused. This `OCIAnyData` can be subsequently constructed using the `OCIAnyDataConvert()` call or it can be constructed piece-wise using the `OCIAnyDataAttrSet()` or the `OCIAnyDataCollAddElem()` calls.

Comments

This call returns this skeleton instance through the `OCIAnyData` parameter which can be constructed subsequently by invoking the OCIAnyData API.

Note: No destruction of the old value is done here. It is your responsibility to destroy the old value pointed to by (`*data`) and set (`*data`) to a `NULL` pointer before beginning to make a sequence of these calls. No deep copying (of `OCIType` information or of the data part) is done in the returned `OCIAnyData`. This `OCIAnyData` cannot be used beyond the allocation duration of the `OCIAnyDataSet` (it is like a reference into the `OCIAnyDataSet`). The returned `OCIAnyData` can be reused on subsequent calls to this function, to sequentially add new data instances to the `OCIAnyDataSet`.

## OCIAnyDataSetBeginCreate()

Purpose

Allocates an `OCIAnyDataSet` for the given duration and initializes it with the type information. The `OCIAnyDataSet` can hold multiple instances of the given type.

Syntax

    sword OCIAnyDataSetBeginCreate ( OCISvcCtx      *svchp,
                                     OCIError       *errhp,
                                     OCITypeCode    typecode,
                                     CONST OCIType  *type,
                                     OCIDuration    dur,
                                     OCIAnyDataSet  **data_set );

Parameters

svchp (IN)

  The OCI service context.

errhp (IN/OUT)

  The OCI error handle. If there is an error, it is recorded in `err` and this function returns `OCI_ERROR`. Obtain diagnostic information by calling `OCIErrorGet()`.

typecode (IN)

  Typecode corresponding to the `OCIAnyDataSet`.

type (IN)

  Type corresponding to the `OCIAnyDataSet`. If the typecode corresponds to a built-in type (`OCI_TYPECODE_NUMBER`, and so on), this parameter can be `NULL`. It should be non-`NULL` for user defined types (`OCI_TYPECODE_OBJECT`, `OCI_TYPECODE_REF`, collection types, and so on).

dur (IN)

  Duration for which `OCIAnyDataSet` is allocated. One of the following:

- A user duration that was previously created. It can be created by using `OCIDurationBegin()`.

- A predefined duration, such as `OCI_DURATION_SESSION`.

data_set (OUT)

  Initialized `OCIAnyDataSet`.

Comments

For performance reasons, the `OCIAnyDataSet` will end up pointing to the `OCIType` parameter passed in. It is your responsibility to ensure that the `OCIType` is longer lived (has allocation duration >= the duration of the `OCIAnyData` if the `OCIType` is a transient one, or has allocation/pin duration >= duration of the `OCIAnyData,` if the `OCIType` is a persistent one).

## OCIAnyDataSetDestroy()

Purpose

Frees the `OCIAnyDataSet`.

Syntax

    sword OCIAnyDataSetDestroy ( OCISvcCtx      *svchp,
                                 OCIError       *errhp,
                                 OCIAnyDataSet  *data_set );

Parameters

svchp (IN)

  The OCI service context.

errhp (IN/OUT)

  The OCI error handle. If there is an error, it is recorded in `err` and this function returns `OCI_ERROR`. Obtain diagnostic information by calling `OCIErrorGet()`.

data_set (IN/OUT)

  `OCIAnyDataSet` to be freed.

## OCIAnyDataSetEndCreate()

Purpose

Marks the end of `OCIAnyDataSet` creation. It should be called after constructing all of its instances.

Syntax

    sword OCIAnyDataSetEndCreate ( OCISvcCtx      *svchp,
                                   OCIError       *errhp,
                                   OCIAnyDataSet  *data_set );

Parameters

svchp (IN)

  The OCI service context.

errhp (IN/OUT)

  The OCI error handle. If there is an error, it is recorded in `err` and this function returns `OCI_ERROR`. Obtain diagnostic information by calling `OCIErrorGet()`.

data_set (IN/OUT)

  Initialized `OCIAnyDataSet`.

## OCIAnyDataSetGetCount()

Purpose

Gets the number of instances in the `OCIAnyDataSet`.

Syntax

    sword OCIAnyDataSetGetCount( OCISvcCtx      *svchp,
                                 OCIError       *errhp,
                                 OCIAnyDataSet  *data_set,
                                 ub4            *count );

Parameters

svchp (IN)

  The OCI service context.

errhp (IN/OUT)

  The OCI error handle. If there is an error, it is recorded in `err` and this function returns `OCI_ERROR`. Obtain diagnostic information by calling `OCIErrorGet()`.

data_set (IN/OUT)

  A well-formed `OCIAnyDataSet`.

count (OUT)

  Number of instances in `OCIAnyDataSet`.

## OCIAnyDataSetGetInstance()

Purpose

Returns the `OCIAnyData` corresponding to an instance at the current position and updates the current position.

Syntax

    sword OCIAnyDataSetGetInstance ( OCISvcCtx      *svchp,
                                     OCIError       *errhp,
                                     OCIAnyDataSet  *data_set,
                                     OCIAnyData     **data );

Parameters

svchp (IN)

  The OCI service context.

errhp (IN/OUT)

  The OCI error handle. If there is an error, it is recorded in `err` and this function returns `OCI_ERROR`. Obtain diagnostic information by calling `OCIErrorGet()`.

data_set (IN/OUT)

  A well-formed `OCIAnyDataSet`.

data (IN/OUT)

  `OCIAnyDat`a corresponding to the instance. If (*data) is `NULL`, a new `OCIAnyData` will be allocated for same duration as the `OCIAnyDataSet`. If (`*data`) is not `NULL`, it will be reused.

Comments

Only sequential access to the instances in an `OCIAnyDataSet` is allowed. This call returns the `OCIAnyData` corresponding to an instance at the current position and updates the current position. Subsequently, the OCIAnyData access routines may be used to access the instance.

## OCIAnyDataSetGetType()

Purpose

Gets the type corresponding to an `OCIAnyDataSet`.

Syntax

    sword OCIAnyDataSetGetType ( OCISvcCtx      *svchp,
                                 OCIError       *errhp,
                                 OCIAnyDataSet  *data_set,
                                 OCITypeCode    *tc,
                                 OCIType        **type );

Parameters

svchp (IN)

  The OCI service context.

errhp (IN/OUT)

  The OCI error handle. If there is an error, it is recorded in `err` and this function returns `OCI_ERROR`. Obtain diagnostic information by calling `OCIErrorGet()`.

data_set (IN)

  Initialized `OCIAnyDataSet`.

tc (OUT)

  The typecode corresponding to the type of the `OCIAnyDataSet`.

type (OUT)

  The type corresponding to the `OCIAnyDataSet`. This will be `NULL` if the `OCIAnyData` corresponds to a built-in type.